<!-- HTML header for doxygen 1.8.3.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>AngelScript: Registering a value type</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="test/javascript" src="touch.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('doc_register_val_type.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Registering a value type </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>When registering a value type, the size of the type must be given so that AngelScript knows how much space is needed for it. If the type doesn't require any special treatment, i.e. doesn't contain any pointers or other resource references that must be maintained, then the type can be registered with the flag <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa8ad017ddf25368870b28ee0fba96495a">asOBJ_POD</a>. In this case AngelScript doesn't require the default constructor, assignment behaviour, or destructor as it will be able to automatically handle these cases the same way it handles built-in primitives.</p>
<p>If you plan on passing or returning the type by value to registered functions that uses native calling convention, you also need to inform <a class="el" href="doc_register_val_type.html#doc_reg_val_2">how the type is implemented in the application</a>, but if you only plan on using generic calling conventions, or don't pass these types by value then you don't need to worry about that.</p>
<div class="fragment"><div class="line"><span class="comment">// Register a primitive type, that doesn&#39;t need any special management of the content</span></div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">&quot;pod&quot;</span>, <span class="keyword">sizeof</span>(pod), <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9fc16a8ac0f30f9ff9c6568e0b7be91d" title="A value type.">asOBJ_VALUE</a> | <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa8ad017ddf25368870b28ee0fba96495a" title="A plain-old-data type. Only valid for value types.">asOBJ_POD</a>); assert( r &gt;= 0 );</div>
<div class="line"></div>
<div class="line"><span class="comment">// Register a class that must be properly initialized and uninitialized</span></div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">&quot;val&quot;</span>, <span class="keyword">sizeof</span>(val), <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9fc16a8ac0f30f9ff9c6568e0b7be91d" title="A value type.">asOBJ_VALUE</a>); assert( r &gt;= 0 );</div>
</div><!-- fragment --><dl class="section see"><dt>See Also</dt><dd>The <a class="el" href="doc_addon_std_string.html">string object</a> or the <a class="el" href="doc_addon_math.html">complex type in the math add-on</a> for examples of value types </dd>
<dd>
<a class="el" href="doc_adv_generic_handle.html">Registering a generic handle type</a> for a more specific example of a value type</dd></dl>
<h1><a class="anchor" id="doc_reg_val_1"></a>
Constructor and destructor</h1>
<p>If a constructor or destructor is needed they shall be registered the following way:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> Constructor(<span class="keywordtype">void</span> *memory)</div>
<div class="line">{</div>
<div class="line">  <span class="comment">// Initialize the pre-allocated memory by calling the</span></div>
<div class="line">  <span class="comment">// object constructor with the placement-new operator</span></div>
<div class="line">  <span class="keyword">new</span>(memory) Object();</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">void</span> Destructor(<span class="keywordtype">void</span> *memory)</div>
<div class="line">{</div>
<div class="line">  <span class="comment">// Uninitialize the memory by calling the object destructor</span></div>
<div class="line">  ((Object*)memory)-&gt;~Object();</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">// Register the behaviours</span></div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#ad69bc821a7f1120369c1bd9526f41b9c" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">&quot;val&quot;</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5aa4cf235bfbf72ec03d0f651cea324101" title="Constructor.">asBEHAVE_CONSTRUCT</a>, <span class="stringliteral">&quot;void f()&quot;</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(Constructor), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253" title="A cdecl function that takes the object pointer as the last parameter.">asCALL_CDECL_OBJLAST</a>); assert( r &gt;= 0 );</div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#ad69bc821a7f1120369c1bd9526f41b9c" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">&quot;val&quot;</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a0748a0f3a559354761ce15c2d1de2e51" title="Destructor.">asBEHAVE_DESTRUCT</a>, <span class="stringliteral">&quot;void f()&quot;</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(Destructor), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253" title="A cdecl function that takes the object pointer as the last parameter.">asCALL_CDECL_OBJLAST</a>); assert( r &gt;= 0 );</div>
</div><!-- fragment --><p>Remember to use unique names or namespaces for the wrapper functions, even if you create templated implementations. Otherwise the linker may end up taking the address of the wrong function when registering the wrapper with AngelScript, which is sure to result in unexpected behaviours.</p>
<p>Note that you may need to include the &lt;new&gt; header to declare the placement new operator that is used to initialize a preallocated memory block.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="doc_register_val_type.html#doc_reg_val_3">List constructor</a>.</dd></dl>
<h1><a class="anchor" id="doc_reg_val_2"></a>
Value types and native calling conventions</h1>
<p>If the type will be passed to or from the application by value using native calling conventions it is important to inform AngelScript of its real type in C++, otherwise AngelScript won't be able to determine exactly how C++ is treating the type in a parameter or return value.</p>
<p>To inform AngelScript of actual type in C++ the template function <a class="el" href="angelscript_8h.html#a863f2a1e60e6c19eea9c6b34690dcc00">asGetTypeTraits</a> should preferably be used as it will automatically determine the correct flags to pass to <a class="el" href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6">RegisterObjectType</a> together with the asOBJ_VALUE flag.</p>
<div class="fragment"><div class="line"><span class="comment">// With C++11 the type can be registered with GetTypeTraits</span></div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">&quot;complex&quot;</span>, <span class="keyword">sizeof</span>(complex), <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9fc16a8ac0f30f9ff9c6568e0b7be91d" title="A value type.">asOBJ_VALUE</a> | asGetTypeTraits&lt;complex&gt;()); assert( r &gt;= 0 );</div>
</div><!-- fragment --><p>On some platforms the native calling convention may require further knowledge about the class members that <a class="el" href="angelscript_8h.html#a863f2a1e60e6c19eea9c6b34690dcc00">asGetTypeTraits</a> cannot determine in order to work properly; most notable are the Linux 64bit and Mac OSX 64bit systems with the GNUC compiler. On these systems small classes that do not have a destructor or a copy constructor will have different behaviours depending on the type and order of their members.</p>
<p>AngelScript lets the application give information that cover the most common variants, e.g. the class should be treated as if all members are integers, or it should be treated as if all members are floats.</p>
<table  border="0" cellspacing="0" cellpadding="0">
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa5b8de58c5be3145aaa3e54008fb2edeb">asOBJ_APP_CLASS_ALLINTS</a> &#160; </td><td>The C++ class members can be treated as if all integers </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa12afb6a0fa4ac874ce89815d3611823d">asOBJ_APP_CLASS_ALLFLOATS</a> &#160; </td><td>The C++ class members can be treated as if all floats or doubles </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa244efb813b401b3a6d087c3add802818">asOBJ_APP_CLASS_ALIGN8</a> &#160; </td><td>The C++ class contains members that may require 8byte alignment, e.g. a double. </td></tr>
</table>
<p>If these flags are not informed and AngelScript needs them on the platform, you'll get an error message like "Don't support passing/returning type 'MyType' by value to application in native calling convention on this platform".</p>
<p>It is difficult to explain when one or the other should be used as it requires in-depth knowledge of the ABI for the respective system, so if you find that you really need to use these flags, make sure you perform adequate testing to guarantee that your functions are called correctly by the script engine. If neither of these flags work, and you're not able to change the class to work without them, then the only other option is to use the generic calling convention, preferably with the <a class="el" href="doc_addon_autowrap.html">auto wrappers</a>.</p>
<h2><a class="anchor" id="doc_reg_val_2_nocpp11"></a>
For compilers that don't support C++11</h2>
<p>If your compiler doesn't support C++11 features the <a class="el" href="angelscript_8h.html#a863f2a1e60e6c19eea9c6b34690dcc00">asGetTypeTraits</a> function will not be available. In this case you have no option but to inform the correct flags manually. Be careful to inform the correct flags, because if the wrong flags are used you may get unexpected behaviour when calling registered functions that passes or returns these types by value. Common problems are stack corruptions or invalid memory accesses. In some cases you may face more silent errors that may be difficult to detect, e.g. the function is not returning the expected values.</p>
<p>There are a few different flags:</p>
<table  border="0" cellspacing="0" cellpadding="0">
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa103297ed88696a3c30ec12e533d902c3">asOBJ_APP_CLASS</a> &#160; </td><td>The C++ type is a class, struct, or union </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aafd799c0705cee720a12ceb2838796024">asOBJ_APP_CLASS_CONSTRUCTOR</a> &#160; </td><td>The C++ type has a default constructor </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa18d80c6d92e4bc104955da393c966917">asOBJ_APP_CLASS_DESTRUCTOR</a> &#160; </td><td>The C++ type has a destructor </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa6bf9b7bead31a40e7983538d8cecc3a4">asOBJ_APP_CLASS_ASSIGNMENT</a> &#160; </td><td>The C++ type has a copy assignment operator </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa925febfd30b150d97a84b7c6ee6a8677">asOBJ_APP_CLASS_COPY_CONSTRUCTOR</a> &#160; </td><td>The C++ type has a copy constructor </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa539ede421d313b03464c88cb15f08c75">asOBJ_APP_PRIMITIVE</a> &#160; </td><td>The C++ type is a C++ primitive, but not a float or double </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa7f7690d53d9bfc580e09ac7bf5868175">asOBJ_APP_FLOAT</a> &#160; </td><td>The C++ type is a float or double </td></tr>
<tr>
<td><a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa84a949c5cc6d4d872054baac1a085419">asOBJ_APP_ARRAY</a> &#160; </td><td>The C++ type is an array </td></tr>
</table>
<p>Note that these don't represent how the type will behave in the script language, only what the real type is in the host application. So if you want to register a C++ class that you want to behave as a primitive type in the script language you should still use the flag <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa103297ed88696a3c30ec12e533d902c3">asOBJ_APP_CLASS</a>. The same thing for the flags to identify that the class has a constructor, destructor, assignment operator, or copy constructor. These flags tell AngelScript that the class has the respective function, but not that the type in the script language should have these behaviours.</p>
<p>Observe that the C++ compiler may provide these functions automatically if one of the members of the class is of a type that requires it. So even if the type you want to register doesn't have a declared default constructor it may still be necessary to register the type with the flag asOBJ_APP_CLASS_CONSTRUCTOR. The same for the other functions.</p>
<p>For class types there is also a shorter form of the flags for each combination of the 5 flags. They are of the form <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa12d358962300537f2b0da20106eb270c">asOBJ_APP_CLASS_CDAK</a>, where the existence of the last letters determine if the constructor, destructor, and/or assignment behaviour are available. For example <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa12d358962300537f2b0da20106eb270c">asOBJ_APP_CLASS_CDAK</a> is defined as <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa103297ed88696a3c30ec12e533d902c3">asOBJ_APP_CLASS</a> | <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aafd799c0705cee720a12ceb2838796024">asOBJ_APP_CLASS_CONSTRUCTOR</a> | <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa18d80c6d92e4bc104955da393c966917">asOBJ_APP_CLASS_DESTRUCTOR</a> | <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa6bf9b7bead31a40e7983538d8cecc3a4">asOBJ_APP_CLASS_ASSIGNMENT</a> | <a class="el" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa925febfd30b150d97a84b7c6ee6a8677">asOBJ_APP_CLASS_COPY_CONSTRUCTOR</a>.</p>
<div class="fragment"><div class="line"><span class="comment">// Register a complex type that will be passed by value to the application</span></div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a29c6c087c8c5b5cdb6271cfd161cc5a6" title="Registers a new object type.">RegisterObjectType</a>(<span class="stringliteral">&quot;complex&quot;</span>, <span class="keyword">sizeof</span>(complex), <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa9fc16a8ac0f30f9ff9c6568e0b7be91d" title="A value type.">asOBJ_VALUE</a> | <a class="code" href="angelscript_8h.html#a855d86fa9ee15b9f75e553ee376b5c7aa12d358962300537f2b0da20106eb270c" title="The C++ type is a class with a constructor, destructor, assignment operator, and copy constructor...">asOBJ_APP_CLASS_CDAK</a>); assert( r &gt;= 0 );</div>
</div><!-- fragment --><h1><a class="anchor" id="doc_reg_val_3"></a>
List constructor</h1>
<p>The list constructor is similar to <a class="el" href="doc_reg_basicref.html#doc_reg_basicref_4">the list factory function</a> for reference types. The constructor will receive a pointer to the initialization list buffer in the exact same way, and the expected list pattern should be registered in the same way. The difference is that the list constructor should be registered like a method, just as done for other <a class="el" href="doc_register_val_type.html#doc_reg_val_1">constructors</a>.</p>
<p>Example registration of a list constructor:</p>
<div class="fragment"><div class="line">engine-&gt;<a class="code" href="classas_i_script_engine.html#ad69bc821a7f1120369c1bd9526f41b9c" title="Registers a behaviour for the object type.">RegisterObjectBehaviour</a>(<span class="stringliteral">&quot;vector3&quot;</span>, <a class="code" href="angelscript_8h.html#a7e38df5b10ec8cbf2a688f1d114097c5a04c0b561986c6814e8a54ce3679178a2" title="Constructor used exclusively for initialization lists.">asBEHAVE_LIST_CONSTRUCT</a>, <span class="stringliteral">&quot;void f(int &amp;in) {float, float, float}&quot;</span>, ...);</div>
</div><!-- fragment --><dl class="section see"><dt>See Also</dt><dd><a class="el" href="doc_addon_math.html">The complex math add-on</a> for an example value type with a list constructor. </dd></dl>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Sun Dec 18 2016 12:35:29 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.3.1 </li>
  </ul>
</div>
</body>
</html>
